home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 1.iso / ARGONET / PD / SOUND / MP3CONV.ZIP / !MP3Conv / docs / readme < prev    next >
Text File  |  1997-04-06  |  12KB  |  253 lines
  1.  
  2.             mpeg3play version 0.9.6
  3.                  April 6, 1997
  4.  
  5.  
  6. Home page:  The Solaris Helpers Page at
  7.             http://home1.swipnet.se/%7Ew-10694/helpers.html
  8.  
  9. Authors:    ISO/MPEG working groups, Fraunhofer Institute and
  10.         Johan Hagman <Johan.Hagman@mailbox.swipnet.se>
  11.  
  12.  
  13. mpeg3play is an MPEG layer 2 and layer 3 audio decoder/player for Unix,
  14. based on public ISO/MPEG audio decoder source code.
  15.  
  16. The original software is a slow but portable MPEG audio to AIFF decoder,
  17. impossible to use as a real-time player. I have optimized the source to
  18. make it possible to use the decoder for real-time playback and have
  19. modified it for output to the Solaris/SunOS audio device. Only 16-bit
  20. (CD-quality) audio devices are currently supported. The various data files
  21. that the original decoder needs at runtime are also integrated to make it
  22. a self-contained executable.
  23.  
  24. Version 0.9 for Solaris/SPARC was the initial release of the player, but
  25. it can currently also be compiled for Linux (since version 0.9.1), HPUX
  26. (version 0.9.3), Amiga (version 0.9.4), IBM AIX (version 0.9.5) and
  27. FreeBSD, Solaris/x86, SunOS 4.x (version 0.9.6). Many thanks to the
  28. following people for their suggestions, optimizations and porting efforts
  29.  
  30.    Tim Newsome <drz@froody.bloke.com>           Linux
  31.    Damien Clermonte <clermond@esiee.fr>           HPUX
  32.    Troels Walsted Hansen <troels@stud.cs.uit.no>   Amiga
  33.    Terje Malmedal <terje.malmedal@usit.uio.no>       AIX
  34.    Dan Nelson <dnelson@emsphone.com>           FreeBSD
  35.    Michael Cheng <mcheng@faraday.dialix.com.au>    Amiga
  36.    Fredrik Hubinette <hubbe@lysator.liu.se>        Linux
  37.  
  38. The -h (help) command line option shows the usage:
  39.  
  40. % mpeg3play -h
  41. +---------------------------------------+
  42. |   mpeg3play version 0.9.6, 6-Apr-97   |
  43. +---------------------------------------+
  44. This is an MPEG audio layer 2 and layer 3 decoder/player
  45. based on public ISO/MPEG audio decoder source code. Solaris
  46. port and optimizations by Johan.Hagman@mailbox.swipnet.se.
  47.  
  48. Copyright (C) 1996, 1997 by Johan Hagman.
  49. This program is free software.
  50.  
  51. usage: mpeg3play [-v] [-h] [-f] [-o outfile.aiff] filename
  52.   -v          enable verbose mode
  53.   -h          display program help information
  54.   -f          fork off new player and return
  55.   -o outfile  write an AIFF output PCM sound file
  56.   filename    bit stream of encoded audio ("-" means stdin)
  57.  
  58. ----------------------------------------------------------------------
  59.  
  60. PLATFORM-SPECIFIC INFORMATION
  61.  
  62. Solaris/SPARC:
  63.  
  64. The Solaris/SPARC binary available from the Solaris Helpers page includes
  65. some assembly optimizations in addition to the C optimizations in the source
  66. distribution.
  67.  
  68. Linux and FreeBSD:
  69.  
  70. mpeg3play 0.9.6 (and later versions) tries to nice -11 in order to raise
  71. the priority of the mpeg3play process above i.e. graphics operations
  72. and obtain better sound quality. To take advantage of this, you must run
  73. mpeg3play as root or install it as setuid root.
  74.  
  75. ----------------------------------------------------------------------
  76.  
  77. ABOUT THE SOURCE CODE
  78.  
  79. mpeg3play is developed on Solaris 2.4 using Sun SPARCompiler C 4.0.
  80.  
  81. A number of customization flags can be set in the makefile:
  82.  
  83. FSINGLE        Use single precision math.
  84. OPTIMIZE    Select optimized C routines. If this is not defined,
  85.         the original, slow code is selected.
  86. BUILTIN_TABLES    Build lookup tables into the binary. Must always be
  87.         defined with this source distribution.
  88. DETECT_CLIP    Check and correct clipped samples. Slows down the player
  89.         somewhat, but sounds better with (too) loud audio samples.
  90. ASM_OPTIMIZE    Select optimized assembly functions. As shipped, the
  91.         following function is expected to be optimized in
  92.         some external file: II_dequantize_sample()
  93. INT_MATH    Select integer math routines. A somewhat optimized integer
  94.         math version of the function SubBandSynthesis() is included
  95.         in decode.c. But fp math is faster than integer math on CPUs
  96.         like SPARC and Pentium, so this is normally not a good way
  97.         to optimize anyway.
  98.         
  99. This is a runtime profile that lists the most important functions to
  100. optimize for playback of layer 3 audio:
  101.  
  102. granularity: each sample hit covers 2 byte(s) for 0.05% of 22.21 seconds
  103.  
  104.    %  cumulative    self              self    total          
  105.  time   seconds   seconds    calls  ms/call  ms/call name    
  106.  23.4       5.20     5.20   170928     0.03     0.03  SubBandSynthesis [3]
  107.  14.8       8.48     3.28   303872     0.01     0.01  inv_mdct [6]
  108.  12.6      11.28     2.80     9496     0.29     0.29  III_dequantize_sample [7]
  109.   9.8      13.45     2.17     9496     0.23     0.39  III_hufman_decode [4]
  110.   6.8      14.95     1.50      676     2.22     2.22  _write [10]
  111.   6.7      16.43     1.48     4748     0.31     0.31  III_stereo [11]
  112.   3.6      18.18     0.80  1052029     0.00     0.00  huffman_decoder [9]
  113.   3.2      18.88     0.71  4775924     0.00     0.00  hget1bit [12]
  114.   1.5      20.25     0.34     9496     0.04     0.04  III_antialias [15]
  115.   1.4      20.56     0.31   303872     0.00     0.01  III_hybrid [5]
  116.   1.4      20.86     0.30     9496     0.03     0.03  III_reorder [16]
  117.   1.4      21.16     0.30     4748     0.06     0.37  out_fifo [8]
  118.   0.9      21.36     0.21   767752     0.00     0.00  getbits [14]
  119.   0.5      21.61     0.12   214608     0.00     0.00  hgetbits [22]
  120.   0.5      21.72     0.11     9001     0.01     0.01  _memcpy [23]
  121.   0.5      21.82     0.10       93     1.08     1.08  _read [24]
  122.   0.5      21.92     0.10        7    14.29    14.29  _ioctl [25]
  123.   0.4      22.00     0.08   659390     0.00     0.00  hputbuf [26]
  124.   0.1      22.10     0.02    72752     0.00     0.00  get1bit [33]
  125.   0.1      22.12     0.02     9496     0.00     0.01  III_get_scale_factors [18]
  126.   0.1      22.14     0.02      182     0.11     0.83  refill_buffer [17]
  127.   0.0      22.15     0.01   179285     0.00     0.00  hsstell [38]
  128.   0.0      22.16     0.01    25371     0.00     0.00  _memset [40]
  129.   0.0      22.17     0.01    10010     0.00     0.00  __tan [41]
  130.   0.0      22.18     0.01     2768     0.00     0.00  __cos [42]
  131.   0.0      22.19     0.01     2374     0.00     0.03  III_get_side_info [27]
  132.   0.0      22.20     0.01        4     2.50     2.50  _smalloc [43]
  133.   0.0      22.20     0.01                            huffman_coder [47]
  134.   0.0      22.21     0.01                            look_ahead [48]
  135.   0.0      22.21     0.01                            update_CRC [49]
  136.   0.0      22.21     0.00     9496     0.00     0.00  initialize_huffman [44]
  137.   0.0      22.21     0.00     4748     0.00     0.00  main_data_slots [53]
  138.   0.0      22.21     0.00     2375     0.00     0.00  end_bs [54]
  139.   0.0      22.21     0.00     2374     0.00     0.00  decode_info [37]
  140.   0.0      22.21     0.00     2374     0.00     0.00  hdr_to_frps [55]
  141.   0.0      22.21     0.00     2374     0.00     0.00  seek_sync [51]
  142.   0.0      22.21     0.00     2374     0.00     0.00  sstell [56]
  143.  
  144.  
  145. And this is the corresponding profile for playback of layer 2 files:
  146.  
  147. granularity: each sample hit covers 2 byte(s) for 0.06% of 16.12 seconds
  148.  
  149.    %  cumulative    self              self    total          
  150.  time   seconds   seconds    calls  ms/call  ms/call name    
  151.  44.0       7.09     7.09   245376     0.03     0.03  SubBandSynthesis [3]
  152.  17.6       9.92     2.83    40896     0.07     0.07  II_dequantize_sample [5]
  153.  13.6      12.12     2.20      968     2.27     2.27  _write [6]
  154.   8.9      13.56     1.44    40896     0.04     0.05  II_buffer_sample [7]
  155.   4.7      14.32     0.76  2363383     0.00     0.00  getbits [8]
  156.   4.2      14.99     0.67    40897     0.02     0.07  out_fifo [4]
  157.   2.6      15.41     0.42    40896     0.01     0.01  II_denormalize_sample [9]
  158.   0.6      15.93     0.10        7    14.29    14.29  _ioctl [12]
  159.   0.1      16.07     0.02     3408     0.01     0.05  II_decode_scale [10]
  160.   0.1      16.09     0.02                            look_ahead [23]
  161.   0.1      16.10     0.01     3408     0.00     0.00  decode_info [24]
  162.   0.1      16.11     0.01      349     0.03     0.11  refill_buffer [15]
  163.   0.0      16.12     0.01                            create_syn_filter [28]
  164.   0.0      16.12     0.00    20448     0.00     0.00  get1bit [31]
  165.   0.0      16.12     0.00     3409     0.00     0.00  end_bs [32]
  166.   0.0      16.12     0.00     3409     0.00     0.00  seek_sync [29]
  167.   0.0      16.12     0.00     3409     0.00     0.00  sstell [33]
  168.   0.0      16.12     0.00     3408     0.00     0.01  II_decode_bitalloc [16]
  169.   0.0      16.12     0.00     3408     0.00     0.00  hdr_to_frps [34]
  170.   0.0      16.12     0.00     3408     0.00     0.00  pick_table [35]
  171.   0.0      16.12     0.00     2048     0.00     0.00  __cos [278]
  172.   0.0      16.12     0.00     1917     0.00     0.00  __libmopt__rem_pio2 [279]
  173.   0.0      16.12     0.00      959     0.00     0.00  __libmopt__k_cos_ [280]
  174.   0.0      16.12     0.00      959     0.00     0.00  sound_write [36]
  175.   0.0      16.12     0.00      958     0.00     0.00  __libmopt__k_sin_ [281]
  176.   0.0      16.12     0.00      523     0.00     0.00  _memcpy [282]
  177.   0.0      16.12     0.00      351     0.00     0.08  fread [17]
  178.  
  179.  
  180. The original source code for the decoder can be found in the file
  181. ftp://ftp.tnt.uni-hannover.de/pub/MPEG/audio/mpeg2/software/
  182. technical_report/dist08.tar.gz
  183.  
  184. To make it easier to update and improve mpeg3play, I would like to be
  185. notified of enhancements to this source, so that they can be merged
  186. into future versions of mpeg3play.
  187.  
  188. ----------------------------------------------------------------------
  189.  
  190. KNOWN PROBLEMS
  191.  
  192. - Audio streaming through Netscape sometimes fail (probably a caching
  193.   issue, try to clear the Netscape cache if this happens).
  194.  
  195. - Cannot play some 16kbps mono files. This is probably due to the very
  196.   crude implementation of bitstream synchword detection.  It may not be
  197.   able to correctly decode valid bitstreams which have false synchword
  198.   patterns in the ancillary data portion of the bitstream.
  199.  
  200. - mpeg3play makes the Linux audio driver leak memory (presumably by not
  201.   cleaning up nicely once it's done).
  202.  
  203. ----------------------------------------------------------------------
  204.  
  205. HISTORY
  206.  
  207. 16-Dec-96  0.9      - The initial Solaris/SPARC release.
  208.  
  209. 30-Jan-97  0.9.1  - Code cleanups to remove compiler warnings, audio device
  210.             initialization moved to its own function, implementation
  211.             of SubBandSynthesis was slightly changed.
  212.           - The source was ported to Linux.
  213.  
  214. 31-Jan-97  0.9.2  - Some additional optimizations, single precision floats
  215.             (-DFSINGLE) now works on Linux.
  216.  
  217. 2-Feb-97   0.9.3  - The source was ported to HPUX 9.05, minor optimizations.
  218.  
  219. 16-Feb-97  0.9.4  - System-dependent audio routines were moved into separate
  220.             files audio-<platform>.c.
  221.           - Amiga is now supported.
  222.           - SubBandSynthesis was optimized to reduce the CPU load from
  223.             65% to 56% for a typical layer 3 file.
  224.  
  225. 23-Feb-97  0.9.5  - Several functions were optimized to reduce the CPU load
  226.             by another 12% to 25% (on Solaris, with my test files).
  227.           - Support for IBM AIX was added.
  228.  
  229. 6-Apr-97   0.9.6  - A simple man page was included.
  230.           - Makefile and audio routine changes to support three more
  231.             operating systems: FreeBSD, Solaris/x86, SunOS 4.x
  232.           - Command line switch -r added for Amiga (only) to enable
  233.             raw audio output.
  234.           - SNDCTL_DSP_SETFRAGMENT ioctl and nice(-11) for Linux
  235.             and FreeBSD to improve sound quality.
  236.           - SubBandSynthesis optimizations, implemented using a
  237.             fast cosine transform. This change reduces the CPU load
  238.             by about 10% to 20%.
  239.  
  240. ----------------------------------------------------------------------
  241.  
  242.    Copyright (C) 1996, 1997 by Johan Hagman
  243.  
  244. mpeg3play is distributed "as is" at no additional charge. It can
  245. be used freely for any purpose, but may not be sold commercially.
  246.  
  247. Johan Hagman disclaims all warranties with regard to this software,
  248. including all implied warranties of merchantability and fitness.
  249. In no event will Johan Hagman be liable for direct, incidental or
  250. consequential damages resulting from loss of data or business
  251. opportunities, resulting from mpeg3play, or any part of same,
  252. either alone or in conjunction with other programs.
  253.